/* file name  : SignalingContext.java
 * authors    : Saikat Guha <saikat@cs.cornell.edu>
 * created    : Fri 23 Sep 2005 10:18:25 PM EDT
 * copyright  : GNU Lesser General Public License version 2.1 or later
 * 
 * Copyright (C) 2005 Saikat Guha <saikat@cs.cornell.edu>
 * 
 * This library is free software; you can redistribute it and/or modify it under the terms
 * of the GNU Lesser General Public License as published by the Free Software Foundation;
 * either version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 *  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License along with this
 * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307 USA
 * 
 *
 * modifications:
 * * Fri 23 Sep 2005 Saikat Guha <saikat@cs.cornell.edu>
 *   - Initial release
 */
package net.nutss;

import java.net.URI;
import java.net.UnknownHostException;
import java.io.IOException;

/**
 * Abstracts a signaling service
 *
 * @author Saikat Guha
 * @version %I%, %G%
 */
public interface SignalingContext {

    /**
     * Registers the socket that will receive events.
     *
     * @param selector Selector to register with
     * @return Key for regristration
     */

    /**
     * Retrieves a signaling message after activity on the signaling channel.
     *
     * @param key Key for socket event
     * @return message retrieved
     * @throws IOException if a socket error occurs
     */
    SignalingMessage receive(byte[] bbuf) throws IOException;

    /**
     * Sends a signaling message.
     *
     * @param msg message to send
     * @throws IOException if a socket error occurs
     */
    void send(SignalingMessage msg) throws IOException;

    /**
     * Registers a local endpoint with the signaling service.
     *
     * @param localAddress signaling address for the local endpoint
     * @return Continuation to refresh registration if needed, null otherwise
     * @throws UnknownHostException if registration server cannot be found
     */
    Continuation register(URI localAddress,STUNTSelector sel) throws UnknownHostException;

    /**
     * Creates a signaling message
     *
     * @param localAddress source signaling address
     * @param remoteAddress destination signaling address
     * @param payload message payload
     * @return newly allocated message
     */
    SignalingMessage createMessage(URI localAddress, URI remoteAddress, Object payload);

    /**
     * Creates a reply to a signaling message
     *
     * @param msg message to reply
     * @param payload message payload
     * @return newly allocated reply message
     */
    SignalingMessage createReply(SignalingMessage msg, Object payload);

    /**
     * Modifies a signaling message.
     *
     * @param msg message to modify
     * @param payload message payload
     * @return modified message
     */
    SignalingMessage setMessage(SignalingMessage msg, Object payload);

    /**
     * Closes a signaling channel.
     */
    void close();

}
